
.\" -*- NROFF -*-
.\" 
.TH "lush" "1" "" "" "Development"
.SH "NAME"
lush2 \- Lisp Universal Shell

.SH "SYNOPSIS"
.B lush2 [@initfile] [lushfile ...args...]

.SH "DESCRIPTION"
\fIlush2\fP starts the Lisp Universal Shell.

Lush is an object-oriented Lisp interpreter/compiler with features
designed to please people who want to prototype large numerical 
applications. Lush includes an extensive library of vector/matrix/tensor
manipulation, a set of graphic functions, a simple GUI toolkit,
and interfaces to various libraries such as OpenGL, SDL, the SGI
Multimedia library (video/audio grabbing) , the Numerical Recipes 
library, and others. Lush is an ideal frontend script language for 
programming projects written in C or other languages.


.SH "RUNNING LUSH INTERACTIVELY"
Online help on the standard library is available 
by typing (helptool) at the Lush prompt. You can 
leave Lush by typing CTRL-D at the prompt.

On startup, Lush loads various libraries from the sys and lsh 
directories, as well as a .lushrc file in the user's home directory.
It is recommended to add a directory lsh in your home directory and
to include the line (addpath "your-home-directory/lsh") to your .lushrc
so that your own Lush programs are found in Lush's search path.

It is quite convenient to run Lush from within Emacs, 
which can be done by creating somewhere in your path a symbolic 
link named "lisp" to the lush executable. Then, type ESC-X run-lisp
in Emacs. It is probably a good idea to add the following line
in your .emacs so Emacs switches to Lisp mode when editing a Lush file:

  (setq auto-mode-alist (append (cons "\\.lsh$" 'lisp-mode) auto-mode-alist))


.SH "RUNNING NON-INTERACTIVE LUSH SCRIPTS"
In Unix, Lush can be used to write scripts that can be
called from a shell prompt (like shell or Perl scripts).
A list of command-line arguments are put in the argv variable.

Here is an example: create a file (say "capargs") with the following 
content (replacing the first line by the path to your lush executable):

  #!/bin/sh
  exec lush "$0" "$@"
  !#
  (printf "capitalizing the arguments:\n")
  (each ((arg argv)) (printf "%s %s\n" arg (upcase arg)))

then, make capargs executable: chmod a+x capargs.
You can now invoke capargs at the shell prompt:

  % capargs asd gfdf
  capitalizing the arguments:
  capargs CAPARGS
  asd ASD
  gfdf GFDF

.SH "FILES"
.PD 0
.TP 2
/usr/share/lush2
.PP
.RS
The top of the Lush directory structure
.RE
.TP 2
/usr/share/lush2/src
.PP
.RS
Source code of the interpreter
.RE
.TP 2
/usr/share/lush2/sys
.PP
.RS
Core libraries (lush sources) without which Lush cannot run.  
A minimal/customized version of Lush needs only that directory to run.
.RE
.TP 2
/usr/share/lush2/etc
.PP
.RS
Various shell scripts and utilities
.RE
.TP 2
/usr/share/lush2/include
.PP
.RS
.h files
.RE
.TP 2
/usr/share/lush2/lsh
.PP
.RS
Library files (lush sources) that are part of the standard distribution. 
Although they are not required for Lush to run, life would really suck without them.
.RE
.TP 2
/usr/share/lush2/packages
.PP
.RS
Library files (lush sources) for special applications or platforms, 
or programs that have been contributed by users and cannot be assumed 
to be present/working in all installations of Lush.
.RE
.TP 2 
/usr/share/lush2/local
.PP
.RS
Lush libraries that are specific to your site.
.RE
.TP 2
~/.lush2/lushrc.lsh  
.PP
.RS
Personal Lush initialization file
.RE
.PD

.SH "AUTHORS"
This man page was written by Kevin Rosenberg for the Debian Linux
distribtion as Lush does not come with a man page.
 
Lush was begun by Leon Bottou and Yann LeCun. Contributors include:
Patrice Simard, Yoshua Bengio, Jean Bourrelly, Patrick Haffner, Pascal
Vincent, Sergey Ioffe, Ralf Juengling and many others.


.SH "HISTORY"
Lush is the direct descendant of the SN system. SN was first developed 
as a neural network simulator with a Lisp-like scripting language.
The project was started in 1987 by Leon Bottou and Yann LeCun, and 
rewritten several times since then. SN was used at AT&T for many research 
projects in machine learning, pattern recognition, and image processing. 
Its various incarnations were used at AT&T Bell Labs, AT&T Labs, the Salk 
Institute, the University of Toronto, Universite of Montreal, UC Berkeley, 
and many other research institutions. The commercial versions of SN were 
used in several large companies as a prototyping tool: Thomson-CSF, ONERA.

.SH "SEE ALSO"
Use (helptool) in an interactive lush session for browsing of online
documentation.

